Multimedia Jumpstart/Multimedia Microsoft Jumpstart Version 1.1a (Microsoft).BIN/develpmt/source/vbsprsrc/vbsprite.txt

Text File | 1994-02-15 | 8.0 KB | 194 lines

    VBSPRITE.DLL -- a DLL that does sprites from VB.

    USER'S MANUAL

    TABLE OF CONTENTS

        Chapter Zero:  Legal Mumbo-Jumbo
        Chapter One:   What are SpriteWindows?
        Chapter Two:   Where did you get that pBackgroundDIB, anyway?
        Chapter Three: How do I make DIBs into Sprites?
        Chapter Four:  What can I do with sprites besides create them?
        Chapter Five:  How do I clean up this mess??
        Chapter Six:   What are the declare statements for this DLL?
        Chapter Seven: Do You Have Any Sample Code?
        Chapter Eight: How Come This Can Only Be Used From VB?
        Chapter Nine:  What Do I Do if it Doesn't Work?


------------------------------------------------------------------page break----


        Chapter Zero: Legal Mumbo-Jumbo

THIS CODE AND INFORMATION IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A PARTICULAR
PURPOSE. Copyright (c) 1993  Microsoft Corporation.  All Rights Reserved.


        Chapter One: What are SpriteWindows?

In order for sprites to be drawn on the screen, a number of different things
need to be brought together.  There needs to be a window, a bunch of sprites,
and an off-screen bitmap.  The off-screen bitmap is so that we don't see
flickering as sprites are redrawn.  (Think for a minute about what would happen
without it and you'll see why it is needed).

The structure that does this in VBSPRITE.DLL is the SpriteWindow.  It has a
handle to an hWnd (the real window), a linked list of sprites, and a handle
to the off-screen bitmap.

When using sprites, the SpriteWindow must be created first.  Two calls are
needed to create it.

    pSpriteWnd = CreateSpriteWindow(hWnd)

This creates the SpriteWindow with a handle to the real window it will draw to.
And:
    SetBackground(pSpriteWnd, pBackgroundDIB)

This sets the background DIB to the one you specify, and creates an off-screen
bitmap of the same size.  By the way, all pointers are declared as VB "Long"
(32-bit) variables.


        Chapter Two: Where did you get that pBackgroundDIB, anyway?

DIBs (Device-Independent Bitmaps, more commonly known as .BMP files) are loaded
by LoadDIB:

    pDIB = LoadDIB("filename.bmp")

pDIB will be NULL (i.e. 0) if LoadDIB failed for some reason.

(The sample app that comes with this DLL calls them .DIB files.  They can be
created with BitEdit; PaintBrush is not recommended because it screws around
with the palettes without telling you).


        Chapter Three: How do I make DIBs into Sprites?

First of all, make the background and the sprites use the same palette.  (This
makes sense, since they will all be in the same window!)  The pallette must be
a 256-color (8-bit) one, for no good reason except that's how the sprite DLL
is written.  The color in the upper left corner of the bitmap is assumed to be
the transparency color, so make your bitmaps one pixel taller or wider if
necessary.  (This does not apply to background bitmaps, which have no
transparency)

Now, once you have a SpriteWindow created and a background bitmap assigned
to it, create a sprite with:

    pSpriteDIB = LoadDIB("sprite.bmp")
    pMySprite = CreateSprite(pSpriteWnd, pSpriteDIB, x, y, z, UPDATE_SCREEN)

The "z" coordinate here is what's called the z-order.  The z-order
simply determines which sprites appear on top of which others.
(Sorry, no 3-d perspective or ray-traced shadows).

Most of the Sprite calls have a parameter that tells it whether to update or
not.


        Chapter Four: What can I do with sprites besides create them?

You can: 1) move them,

    x = x + 1
    SetSpritePosition pSpriteWnd, pMySprite, x, y, UPDATE_SCREEN

2) change their DIB,

    pNewDIB = LoadDIB("newimage.bmp")
    SetSpriteDIB pSpriteWnd, pMySprite, pNewDIB, UPDATE_SCREEN

3) change their ZOrder,

    SetSpriteZOrder pSpriteWnd, pMySprite, z, UPDATE_SCREEN

4) Make them invisible (or visible),

    SetSpriteVisible pSpriteWnd, pMySprite, False, UPDATE_SCREEN

or 5) See if the user clicked on them.

    pSpriteHit = SpriteHitTest(pSpriteWnd, mouseX, mouseY)


        Chapter Five: How do I clean up this mess??

Generally, you delete the SpriteWindow, and then delete all the DIBs
that it used, including the background DIB.  (These delete commands
delete the objects in memory, not the disk files!).  You can call
DeleteSprite to delete a sprite, DeleteSpriteWindow to delete
a SpriteWindow, and DeleteDIB to delete a DIB.

If you deviate from this procedure, be careful: If you call
DeleteSpriteWindow, don't try afterwards to delete a sprite,
because DeleteSpriteWindow deletes all the sprites in that
SpriteWindow automatically.  (This makes sense -- you can't
reassign the sprite to a new SpriteWindow.  But you could use
the DIB in another window).

On the other hand, if you delete a sprite, you do still need to delete
any DIBs it used.

Consider the following situation: you drew up a musical note in a bitmap,
and made it into a bunch of sprites which all dance around the screen
at the same time.  (You can do this, because you can create more than
one sprite from the same DIB).  One of the notes is no longer wanted
so you call DeleteSprite.  DeleteSprite deletes the DIB and all of
the other sprites suddenly have a big problem...  This is why
DeleteSprite does not delete the DIB.


        Chapter Six: What are the declare statements for this DLL?

const UPDATE_SCREEN = 1
const NO_UPDATE = 0

Declare Function CreateSpriteWindow Lib "VBSPRITE.DLL" (ByVal hWnd As Integer) As Long
Declare Sub DeleteSpriteWindow Lib "VBSPRITE.DLL" (ByVal pSpriteWnd As Long)
Declare Function LoadDIB Lib "VBSPRITE.DLL" (ByVal filename As String) As Long
Declare Sub DeleteDIB Lib "VBSPRITE.DLL" (ByVal pDIB As Long)
Declare Sub SetBackground Lib "VBSPRITE.DLL" (ByVal pSpriteWnd As Long, ByVal pDIB As Long, ByVal bUpdate As Integer)
Declare Function CreateSprite Lib "VBSPRITE.DLL" (ByVal pSpriteWnd As Long, ByVal pSprDib As Long, ByVal initx As Integer, ByVal inity As Integer, ByVal initz As Integer, ByVal bRedraw As Integer) As Long
Declare Sub DeleteSprite Lib "VBSPRITE.DLL" (ByVal pSpriteWnd As Long, ByVal pSprite As Long)
Declare Function SpriteHitTest Lib "VBSPRITE.DLL" (ByVal pSpriteWnd As Long, ByVal x As Integer, ByVal y As Integer) As Long
Declare Sub SetSpritePosition Lib "VBSPRITE.DLL" (ByVal pSpriteWnd As Long, ByVal pSprite As Long, ByVal x As Integer, ByVal y As Integer, ByVal bUpdate As Integer)
Declare Sub SetSpriteZOrder Lib "VBSPRITE.DLL" (ByVal pSpriteWnd As Long, ByVal pSprite As Long, ByVal z As Integer, ByVal bUpdate As Integer)
Declare Sub SetSpriteDIB Lib "VBSPRITE.DLL" (ByVal pSpriteWnd As Long, ByVal pSprite As Long, ByVal pSprDib As Long, ByVal bUpdate As Integer)
Declare Function GetDIBWidth Lib "VBSPRITE.DLL" (ByVal pDIB As Long) As Long
Declare Function GetDIBHeight Lib "VBSPRITE.DLL" (ByVal pDIB As Long) As Long
Declare Sub RepaintSpriteWindow Lib "VBSPRITE.DLL" (ByVal pSpriteWnd As Long)
Declare Sub SetSpriteVisible Lib "VBSPRITE.DLL" (ByVal pSpriteWnd As Long, ByVal pSprite As Long, ByVal bVisible As Integer, ByVal bUpdate As Integer)

        Chapter Seven: Do You Have Any Sample Code?

Yes: SPRDEMO.MAK is a VB project that demonstrates use of VBSPRITE.DLL.

There are 3 sprites, and they all act differently to show off different
things.  Nell (the girl) just sits there until you grab her with the
mouse and drag her around.  The sun/moon sprite bounces off the bottom
of the screen.  Every second or so, it changes from sun to moon, or
moon to sun, and it loses energy on each bounce.  When you click it,
it gives it a boost and it starts bouncing higher.  Finally, the duck
cycles rapidly through four bitmaps.  When you click it, it falls down
to the bottom of the screen.  That should show pretty well how a VB
program can control the behavior of sprites.


        Chapter Eight: How Come This Can Only Be Used From VB?

Actually, anyone can use it.


        Chapter Nine: What Do I Do if it Doesn't Work?

Send email to: [e-mail].

This manual was written entirely using Microsoft(R) Notepad[tm].